Ribbon

Overview

• You can extend the UI configuration of the ribbon with a manifest.
• You can freely configure tabs and groups on the ribbon, and place buttons to call commands and check boxes to display/change the ON/OFF status on the ribbon.

Ribbon element

Ribbon elements that can be expanded with extensions are as follows.

• Tab
• Group
• Single control
  • Button
  • Checkbox
  • Separator
• Composite control
  • Button group
  • Stack panel
  • Menu
  • Split button

Details for each element

tab (tabs element)

• Tabs that make up the ribbon

  

• Property

  Key	Description	Range	Required
  id	An ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  label	Tab label	Arbitrary string	Required
  orderBefore/orderAfter	The ID of the ribbon element that indicates the relative position to add the tab. 2 If not specified, it will be added before the [Help] tab. If a tab with the same ID already exists, no new tab will be added and the existing tab position will remain. Please refer to Predefined ID for system standard built-in ribbon element ID.	A string that represents an ID	-
  visible	Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified.	"true", "false"	-
  groups	Array of groups that make up a tab	Object array	-

• Child element type

  • Group

Group (groups element)

• Group that divides the ribbon tab

  

• Properties

  Key	Description	Range	Required
  id	An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  label	Group label	Any string	Required
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2 For the ID of the system standard built-in ribbon element, refer to Defined ID.	A string that represents an ID	-
  visible	Display state of the target element. Displayed if omitted or specified as true. Hide when false is specified.	"true", "false"	-
  controls	Array of controls to place in the group	Object array	-

• Types of controls that can be placed as child elements

  • Button
  • CheckBox
  • Separator
  • ButtonGroup
  • StackPanel
  • Menu
  • SplitButton

Button (type: Button)

• Command execution button on the ribbon

  

  • You can assign a command to execute when the button is pressed.
  • The enable/disable status and toggle status of the button are linked with the assigned command.

• Properties

  Key	Description	Range	Required
  type	Element type.	"Button"	Required
  id	ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  label	Button label	Arbitrary string	Required
  description	The description displayed in the tooltip	Any string	-
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string representing ID	-
  visible	Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified.	"true", "false"	-
  isEnabled	Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command.	Character string representing the property name	-
  isChecked	The property name that holds the toggle state of the button. If omitted, it is linked to the status of the assigned command.	Character string that represents the property name	-
  imageSmall	PNG file path for the small icon that appears on the button. 3	Character string representing relative path	-
  imageLarge	Large icon PNG file path to display on the button. 3	Character string that represents relative path	-
  command	The ID of the command assigned to the button.	ID string	Required

Check box (type: CheckBox)

• Checkbox

  

  • The display of the check box changes according to the value of the property associated with the isChecked property.
  • Manipulating the checkbox updates the associated property value.

• Property

  Key	Description	Range	Required
  type	Element type.	"CheckBox"	Required
  id	ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  label	Checkbox label	Arbitrary string	Required
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string representing ID	-
  visible	Display state of the target element. Displayed when omitted or specified as true. Specify false to hide.	"true", "false"	-
  isChecked	Property name that holds the checked status	Character string that represents the property name	Required

Separator (type: Separator)

• Separator.

  

• Property

  Key	Description	Range	Required
  type	The type of element.	"Separator"	Required
  id	ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required

ButtonGroup (type: ButtonGroup)

• A container that displays multiple buttons side by side like a toolbar

  

• Property

  Key	Description	Range	Required
  type	Element type.	"ButtonGroup"	Required
  id	An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string representing ID	-
  visible	The display status of the target element. Displayed when omitted or specified as true. Specify false to hide.	"true", "false"	-
  controls	array of controls placed side by side	object array	-

• Types of controls that can be placed as child elements

  • Button (small)
  • Separator

Stack Panel (type: StackPanel)

• A container that displays multiple buttons vertically

  

  • Use this when you want to display small image buttons vertically.

• Property

  Key	Description	Range	Required
  type	Element type.	"StackPanel"	Required
  id	An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string that represents the ID	Required
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string representing ID	-
  visible	Display state of the target element. Displayed if omitted or specified as true. Specify false to hide.	"true", "false"	-
  controls	An array of controls arranged side by side. Up to 3 controls can be placed.	Object array	-

• Types of controls that can be placed as child elements

  • Button (small)
  • SplitButton (small)
  • ButtonGroup
  • CheckBox
  • Menu

Menu (type: Menu)

• A container that displays multiple buttons in a pull-down menu format

  

• Property

  Key	Description	Range	Required
  type	The type of element.	"Menu"	Required
  id	An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string representing ID	Required
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string representing ID	-
  visible	Display state of the target element. Displayed if omitted or specified as true. Hide when false is specified.	"true", "false"	-
  imageLarge	PNG file path of the icon to display on the button.	A string that represents a relative path	-
  controls	array of controls placed side by side	object array	-

• Types of controls that can be placed as child elements

  • Button (small)
  • Separator

Split button (type: SplitButton)

• A container that has the function of a button that can press itself to execute a command, and also displays another button in a pull-down menu format.

  

• Properties

  Key	Description	Range	Required
  type	The type of element.	"SplitButton"	Required
  id	ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1	Character string representing ID	Required
  label	Button label	Arbitrary string	Required
  description	Description displayed in the tooltip	Arbitrary string	-
  orderBefore/orderAfter	ID of the ribbon element that indicates the relative position to add the target element. 2	Character string that represents the ID	-
  visible	Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified.	"true", "false"	-
  isEnabled	Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command.	Character string that represents the property name	-
  isChecked	Property name that holds the toggle state of the button. If omitted, it is linked to the status of the assigned command.	Character string that represents the property name	-
  imageSmall	PNG file path for the small icon that appears on the button. 3	Character string representing relative path	-
  imageLarge	PNG file path of the large icon to display on the button. 3	Character string that represents relative path	-
  command	Command ID assigned to the button	Character string that represents the ID	Required
  controls	Array of controls that are arranged side by side	Object array	-

• Types of controls that can be placed as child elements

  • Menu

Multilingual

• The values of the Label and Description properties can be localized (localized).
• Instead of specifying the display string as the property value, specify it as "% resource string name %" and it will be replaced with the resource string in the localized locale file.

Detail

• For details on multilingual support, refer to Development Guide> Common> Multilingual Support.

Ribbon definition example

{
  "name": "My Extensition",
  "main": "main.cs",
  "lifecycle": "project",
  "baseprofile": "MBD",

  "extensionPoints": {
    "ribbon": {
      "tabs": [
        {
          "id": "MBD",
          "label": "MBD",
          "orderAfter": "System.View",
          "groups": [
            {
              "id": "MbdSync",
              "label": "block",
              "controls": [
                {
                  "id": "MbdSync.CreateBlock",
                  "type": "Button",
                  "imageLarge": "resources/createBlock.png",
                  "command": "myExtension.createBlock"
                },
                {
                  "type": "Menu",
                  "label": "Check block",
                  "isEnabled": "MyProperty1",
                  "imageLarge": "resources/blocks.png",
                  "controls": [
                    {
                      "id": "MbdSync.UpdateBlock",
                      "type": "Button",
                      "imageSmall": "resources/updateBlock.png",
                      "label": "Update block",
                      "description": "Update the block",
                      "command": "myExtension.updateBlock"
                    }
                  ]
                },
                {
                  "type": "StackPanel",
                  "controls": [
                    {
                      "id": "MbdSync.UpdateBlock",
                      "type": "Button",
                      "isChecked": "myProperty2",
                      "imageSmall": "resources/updateBlock.png",
                      "label": "Update block",
                      "description": "Update the block",
                      "command": "myExtension.updateBlock"
                    },
                    {
                      "type": "Separator"
                    },
                    {
                      "id": "MbdSync.UpdateBlock",
                      "type": "Button",
                      "imageSmall": "resources/updateBlock.png",
                      "label": "Update block",
                      "description": "Update the block",
                      "command": "myExtension.updateBlock"
                    }
                  ]
                }
              ]
            },
            {
              "id": "CodeGen",
              "label": "Generate Source Code",
              "controls": [
                {
                  "id": "CodeGen.GenerateCode",
                  "type": "Button",
                  "imageLarge": "resources/generate.png",
                  "command": "myExtension.generateCode"
                }
              ]
            }
          ]
        }
      ]
    },

    "commands": [
      {
        "id": "myExtension.createBlock",
        "execFunc": "createBlock"
      },
      {
        "id": "myExtension.updateBlock",
        "execFunc": "updateBlock"
      },
      {
        "id": "myExtension.generateCode",
        "execFunc": "generateCode"
      }
    ]
  }
}

---

1. -If you specify the same ID as an existing component, it will be merged into the same component. Otherwise, a new component will be created. ↩↩↩↩↩↩↩↩↩

2. -You can specify the ID of the sibling element that indicates the relative position. You can specify either before (orderBefore) or after (orderAfter) the specified element. If not specified for elements other than tabs, they are added to the end of sibling elements. ↩↩↩↩↩↩↩↩

3. -Set either imageSmall or imageLarge. The size of the displayed icon is adjusted according to the layout in the ribbon. Set imageSmall to the elements of StackPanel. ↩↩↩↩